fix: stop reading private aws-cdk-lib Function.environment field by ava-silver · Pull Request #621 · DataDog/datadog-cdk-constructs

ava-silver · 2026-06-23T21:13:11Z

What does this PR do?

Removes all reads of aws-cdk-lib's private Function.environment field from the library. Every read is replaced with a WeakMap-backed tracker that records the library's own addEnvironment calls. Adds a public DatadogLambda.setEnvironment() method so users can seed env vars the construct will respect.

Motivation

Closes #620

aws-cdk-lib changed Function.environment's internal shape in a semver-minor (2.252 → 2.253), breaking cdk synth for all users of sourceCodeIntegration (#596). The v4.0.0 fix re-pointed the access at the new internal shape and raised the peer floor -- it kept the private coupling, so the library remained one CDK refactor away from breaking again.

Three call sites read across the private boundary:

env.ts -- setGitEnvironmentVariables reads DD_TAGS to append git metadata
env.ts -- applyEnvVariables checks each key before writing a default
datadog-lambda.ts -- overrideGitMetadata reads DD_TAGS to rewrite git components

Changes

src/env-tracker.ts (new)

Module-level WeakMap<LambdaFunction, Map<string, string>> (ddEnvTracker) and three helpers -- setTrackedEnv, getTrackedEnv, hasTrackedEnv -- that record every env write the library makes. Internal, not re-exported from index.ts.

src/env.ts

All addEnvironment calls in setGitEnvironmentVariables, applyEnvVariables, and setDDEnvVariables go through setTrackedEnv.
Private field reads replaced with WeakMap lookups.
setGitEnvironmentVariables parameter type tightened from any[] to LambdaFunction[].

src/datadog-lambda.ts

overrideGitMetadata reads DD_TAGS from getTrackedEnv instead of lambdaFunction.environment.map.get(DD_TAGS), removing the any cast. Tag rewriting extracted to an upsertTag helper.
Adds public setEnvironment(lambdaFunction, key, value), which writes through setTrackedEnv so the construct treats the value as one it manages.

README.md

Documents the env var ordering: configure DD_* vars via DatadogLambdaProps; call func.addEnvironment() after addLambdaFunctions() to override; or call setEnvironment() before to seed a value the construct will respect.

Behavior change

Previously the library read the private field to detect whether the user had already set a DD_* var on a function before addLambdaFunctions(), skipping its default if so -- and to append git metadata onto a user-set DD_TAGS. Without a public CDK read API (which does not exist), arbitrary pre-set env vars are no longer visible to the construct. The new contract:

Configure via props (recommended): use DatadogLambdaProps fields (enableDatadogTracing, logLevel, tags, etc.)
Seed a construct-respected value: call datadogLambda.setEnvironment(func, key, value) before addLambdaFunctions(). The construct will not override it, and when source code integration is enabled it appends git metadata (git.commit.sha, git.repository_url) onto a seeded DD_TAGS rather than overriding it. This preserves the prior per-function DD_TAGS + git-metadata workflow.
Override after: call func.addEnvironment("DD_*", value) after addLambdaFunctions() -- CDK's last-write-wins semantics handle this naturally.
Other vars set before addLambdaFunctions() (not via setEnvironment): will be overridden by the library's defaults.

Testing Guidelines

The existing suite covers the tracker migration; two tests were updated to reflect the behavior change (comments explain the new contract), and the overrideGitMetadata tests now assert via Template.fromStack() instead of reading the CDK private field. New tests cover setEnvironment: git metadata appending onto a seeded DD_TAGS, and the construct not overriding a seeded value.

Run locally with yarn test.

Types of Changes

Bug fix
New feature
Breaking change

Check all that apply

This PR's description is comprehensive
This PR contains breaking changes that are documented in the description
This PR introduces new APIs or parameters that are documented and unlikely to change in the foreseeable future
This PR impacts documentation, and it has been updated (or a ticket has been logged)
This PR's changes are covered by the automated tests

ava-silver · 2026-06-23T21:13:26Z

fix: stop reading private aws-cdk-lib Function.environment field #621 👈 (View in Graphite)
main

This stack of pull requests is managed by Graphite. Learn more about stacking.

janine-c

Just some optional writing suggestions 🙂

ahammond · 2026-08-12T23:54:19Z

Can we please get this merged?

ava-silver · 2026-08-12T23:59:02Z

Can we please get this merged?

We'll try to prioritize it, my main concern is that this version of the fix has a behavior change which may break some usage patterns. I have another potential option up as a separate PR, and I'll weight the options with the team before merging either.

Sorry for the delay, and thanks for your patience on this! I just want to make sure we're being careful before potentially releasing a breaking change.

ahammond · 2026-08-13T19:04:09Z

Appreciate the caution, and I get that the behaviour change needs weighing. But ISTM this is being triaged as a minor cleanup. From the consumer side it is major.

The un-patched library reads a private aws-cdk-lib field, so every consumer of sourceCodeIntegration breaks whenever CDK reshapes that internal. #596 was triggered by a semver-minor (2.252 -> 2.253), and the v4.0.0 fix kept the private coupling, so the next break is a when, not an if. We're an engineering org with compliance and audit obligations: dependency upkeep is mandatory, automated, and continuous. A library that can break cdk synth fleet-wide on any CDK minor is a landmine sitting in that pipeline and has already cost me audit findings.

This PR has been open since June 23, and I want to be direct about the consequences. Next week I'll remove our usage of this library and with it Datadog observability support for lambdas. Future observability work will land in our in-house observability platform. I'd rather not deal with this right now, but Datadog's failure to address our ongoing exposure from this issue in a timely way is forcing my hand.

ava-silver · 2026-08-13T20:23:25Z

@ahammond I've chatted with the team, and we'll go through with the current implementation, which includes a breaking change around setting environment variables. I'll work on getting this merged and released in the next couple days so you can migrate to the safer version.

…psert

ava-silver · 2026-08-14T20:00:21Z

@ahammond we're working on some additional changes before we release the next version (with a major version bump). it should be out sometime next week.

This release includes the following commits: 645a9fd Update default layer versions (#671) 0c17e0d chore: remove singleton private access (#670) 7b22fba ADMS: vuln github.com/aws/aws-cdk-go/awscdk/v2 (minor → v2.263.0) [examples/go-stack] (#665) 651cfde chore: sync shared e2e code (#669) 0ba7bca fix: stop reading private aws-cdk-lib Function.environment field (#621) d523307 chore: sync shared e2e code (#668) cbcaaad ADMS: vuln minor upgrades — 11 packages (minor: 4 · patch: 7) (#659) d31e01f ADMS: vuln aws-cdk-lib (minor → 2.263.0) [examples/ecs] (#653) e9b17c0 fix(deps): vuln aws-cdk-lib (minor → 2.263.0) [examples/step-functions-python-stack] (#652) 024979a chore: Update default Lambda layer versions (#660) 3cce6f9 ADMS: vuln minor: aws-cdk-lib · patch: brace-expansion, fast-uri [examples/step-functions-typescript-stack] (#654) 9b5ee70 fix(deps): vuln minor: aws-cdk-lib · patch: brace-expansion [examples/typescript-stack] (#656) 0a8cd5b chore: type check projen configuration (#650) 02ea173 chore: upgrade projen to 0.101.20 and opt back in to the system shell (#646) 44531c2 chore: Update default Lambda layer versions (#649) 03f4e1c chore(deps): upgrade dependencies (#648) 00eb6f7 ADMS: vuln github.com/yuin/goldmark (minor → v1.8.4) [integration_tests/stacks] (#638) 90fc240 Update default layer versions (#647) c68439b ADMS: vuln github.com/yuin/goldmark (minor → v1.8.4) [examples/ecs] (#641) 4caa9a8 ADMS: vuln github.com/yuin/goldmark (minor → v1.8.4) [examples/step-functions-go-stack] (#640) efb0125 ADMS: vuln github.com/yuin/goldmark (minor → v1.8.4) [examples/go-stack] (#639) 2207c94 Update default layer versions (#636) 1740a52 Update default layer versions (#635) d87dde8 ADMS: vuln minor upgrades — 6 packages (minor: 2 · patch: 4) [examples/typescript-stack] (#633) 54539fb ADMS: vuln minor: aws-cdk-lib · patch: brace-expansion [examples/step-functions-typescript-stack] (#631) e39b228 chore: Release v2-4.2.0 (#630) 4778176 Add uk1.datadoghq.com as a supported Datadog site (#629) 24e2b7c chore: add synced e2e shared helpers (#625) 5796e51 ADMS: minor: golang.org/x/net, golang.org/x/sys [examples/lambda] (#610) 5161c51 ADMS: vuln minor upgrades — 7 packages (minor: 3 · patch: 4) [examples/step-functions-typescript-stack] (#616) 8f1fdb7 chore(deps): upgrade dependencies (#609) abdf98a feat: default Lambda layer versions when none provided (#623) 62adf03 chore: update year (#624) 61564e3 ADMS: golang.org/x/sys (minor → v0.46.0) [examples/go-stack] (#613) de1ced3 ADMS: golang.org/x/sys (minor → v0.46.0) [examples/step-functions-go-stack] (#612) 2f18058 ADMS: golang.org/x/sys (minor → v0.46.0) [examples/ecs] (#614) 228b82c ADMS: golang.org/x/sys (minor → v0.46.0) [integration_tests/stacks] (#611) 1f86ecb chore(deps): upgrade dependencies (#608) a6645dd chore: Release v2-4.1.0 (#604) df31444 Add ruby 4 (#603) 09b0213 chore: Release v2-4.0.0 (#602) 0b601b7 fix!: Update tag setting to use addEnvironment for CDK 2.253.0 (#601) 59fdd97 Executing automated changes (#585) e36373b chore: Update CODEOWNERS (#590) d996e79 chore: drop node 20, add node 26 to CI matrix, bump min node to 22 (#595) 155fe53 Executing automated changes (#584) 23a6588 chore: Release v2-3.12.0 (#593) 1f7ae00 Executing automated changes (#587) 2e86385 Executing automated changes (#588) 55f5733 Add us2.ddog-gov.com site (#592) e2f1eef chore(deps): upgrade dependencies (#591) e7fb9d3 chore: bump go examples to datadog-cdk-constructs-go v3 (#589) 762ef11 chore(deps): runtime go runtime go1.25.7 → go1.26.2 [examples/lambda/go] (#583) 72701e4 chore: fix release process (#582) 734e7b4 chore: Release v2-3.11.0 (#581) 92be561 chore(deps): upgrade dependencies (#580) e76461b chore(deps): minor: com.datadoghq:datadog-cdk-constructs, software.amazon.awscdk:aws-cdk-lib [examples/java-stack] (#569) d2969e5 chore(deps): eol minor: github.com/DataDog/datadog-lambda-go, github.com/aws/aws-lambda-go, gopkg.in/DataDog/dd-trace-go.v1 [examples/lambda] (#575) b8a4836 feat(ecs): add apiKeySecretField for Secrets Manager API key selection (#578) f7bae33 fix: fix upgrade workflow broken by yarn berry migration (#579) 1332f72 chore: [SVLS-8827] upgrade to yarn berry and add npm minimal age gate (#577) a3cd4b0 Executing automated changes (#574) 350a83f chore(deps): minor: aws-cdk · patch: @types/node [examples/typescript-stack] (#576) b3fce9d chore: remove axios node lambda example in favor of native fetch (#573) 949e1f0 chore: Replace npx with yarn in CI to prevent supply chain attacks (#565) 65891fe chore: [SECURITY] make yarn installs immutable in CI (#564) fe9d5df chore: Release v2-3.10.0 (#563) f5d7002 fix: set DD_TRACE_CLOUD_PAYLOAD_TAGGING env vars to '' instead of $.* by default (#562) cc3b323 chore: [Security] Pin GitHub Actions to a full-length commit SHA (#560) ac4f865 Executing automated changes (#558) 10a24c0 Executing automated changes (#556) 45b9e5d Executing automated changes (#557) 70d9a18 Executing automated changes (#550) dbfe6ef Executing automated changes (#549) f69edaf Executing automated changes (#552) b9602c8 Executing automated changes (#554) 203b5cc Executing automated changes (#548) 8ff27cb chore(deps): upgrade dependencies (#547) 341dc20 Executing automated changes (#545) b06e767 Executing automated changes (#546) fc1c0c8 Executing automated changes (#543) 013dc8c Executing automated changes (#542) 09f4d41 Executing automated changes (#540) ae47440 Executing automated changes (#541) 46ec20d chore: npx projen upgrade (#539) ac494ba Ensure reasonable layer version defaults and links (#538) 529e119 chore: Release v2-3.9.0 (#537) 1e6cdc7 feat: grant decrypt permissions for encryption secrets passed to apiKeySecret (#525) 3ccaa47 chore(deps): upgrade dependencies (#536) 353b31e chore: Release v2-3.8.0 (#532) dc06828 feat: ECS Explorer Configuration (#533) 58b26a2 chore(deps): upgrade dependencies (#531) 6c96a0c Added a shortlink to the ExtensionLayerVersion release page (#485) 143f84e feat: Add DD_API_KEY_SSM_ARN suport for AWS lambda (#527) d1ebcda chore: Release v2-3.7.0 (#530) 6779681 Add support for .NET 10 (#529) 0b90f67 chore(deps): upgrade dependencies (#526) 2bab6dd Revert "Add DD_API_KEY_SSM_ARN suport for AWS lambda" 028dbfa Add DD_API_KEY_SSM_ARN suport for AWS lambda 3c121bb chore: Remove CDK v1 from docs (#523) ff1787f chore(deps): upgrade dependencies (#518) 0cce892 chore: fix CI (#524) 63ccb46 chore: deduplicate unit tests (#522) 1331094 chore: use node 20 for min version (#521) 39f8a41 feat: [SVLS-8268] migrate to OIDC auth (#520) 392282d chore: migrate to serverless onboarding managed team (#519) 3e53fe3 chore(deps): upgrade dependencies (#517) fc3e7ce chore: Release v2-3.6.0 (#516) 308dfab chore(deps): upgrade dependencies (#515) e7973ab Support Ruby 3.4 (#513) a290f42 chore: Release v2-3.5.1 (#514) 540b096 chore: Release v2-3.5.0 (#512) 239bb4c Update log source to datadog-agent (#511) 31a9f6e chore: Fix typos using Cursor (#412) c13c962 add java 25 (#508) 9119102 chore(deps): upgrade dependencies (#504) c52adba feat: add java package (#502) 445306d chore: update gitignore (#510) af3a746 Only set AWS_LAMBDA_EXEC_WRAPPER if extension is configured (#509) 4238dda feat: Allow Configurable Logging Definitions for Application Containers (#507) 8e1c606 chore: Release v2-3.4.0 (#506) aa6245c add node 24 runtime (#505) bb6488c Adding Python 3.14 runtiming (#500) 569f810 [CHORE] update CI to node 24 (#503) 44a670a [SVLS-5911] always add DD_ env vars (#501) 69d4399 chore: Release v2-3.3.0 (#499) 7eac3f7 chore(deps): upgrade dependencies (#498) 8d6f0ea feat(ecs_fargate): [CONTP-921] Configure ROFS support for ecs datadog agent (#495) 0c0c0ea chore(deps): bump aws-cdk-lib (#497) 19b2463 chore(deps): upgrade dependencies (#496) 8106944 chore(deps): upgrade dependencies (#494) 9c8fbed Add example of passing in props to ECS Fargate task definition (#491) 2010667 Update README to show all lambda runtimes supported (#492) 8626475 chore(deps): bump brace-expansion in /examples/ecs/typescript-stack (#467) c5b7891 chore(deps): upgrade dependencies (#490) 1f3761c chore(deps): upgrade dependencies (#489) 6d4721c feat(appsec): deprecate enableDatadogASM in favor of datadogAppSecMode (#486) e65cc91 chore(deps): upgrade dependencies (#481) cae484c chore: Update unsupported node version test to not call determineLatestNodeRuntime (#487) 869a5ed chore: Release v2-3.2.2 (#484) 32bdcca feat(CONTP-922): Expose ability to provide custom ecs.FireLenseLogDriver upon log driver creation (#482) b6a0e0f chore(deps): bump axios from 1.8.2 to 1.12.0 in /examples/lambda/node (#480) 9ba1d5e chore(deps): upgrade dependencies (#478) e55135b chore(deps): upgrade dependencies (#477) a8f523e chore(deps): upgrade dependencies (#476) 94d9a75 Add version.json update to create release script (#475) 0f8a632 Release v2-3.2.1 (#474) e5003ae chore: Add create-release script (#473) a63400f chore(deps): upgrade dependencies (#472) 34c7b90 Allow unit tests to run in gitlab (#471) 0caa064 chore(deps): upgrade dependencies (#470)

This comment has been minimized.

Sign in to view

ava-silver changed the title ~~[SVLS-9359] stop reading private aws-cdk-lib Function.environment field~~ fix: stop reading private aws-cdk-lib Function.environment field Jun 23, 2026

ava-silver mentioned this pull request Jun 23, 2026

datadog-cdk-constructs-v2 reads aws-cdk-lib's **private** Function.environment internals — it broke cdk synth once (2.253.0), and the "fix" dug deeper instead of respecting the interface #620

Closed

ava-silver marked this pull request as ready for review June 24, 2026 21:28

ava-silver requested review from a team as code owners June 24, 2026 21:28

ava-silver requested a review from TalUsvyatsky June 24, 2026 21:28

ava-silver force-pushed the ava.silver/svls-9359/stop-reading-private-cdk-function-environment-field branch from 31ab410 to 5b06be5 Compare June 24, 2026 21:32

janine-c approved these changes Jun 25, 2026

View reviewed changes

Comment thread README.md Outdated

ava-silver mentioned this pull request Jun 25, 2026

fix: apply Datadog env vars via synth-time CDK aspect #622

Closed

2 tasks

ava-silver force-pushed the ava.silver/svls-9359/stop-reading-private-cdk-function-environment-field branch from 5b06be5 to 062d08f Compare June 25, 2026 21:19

ava-silver added 5 commits August 13, 2026 16:53

[SVLS-9359] stop reading private aws-cdk-lib Function.environment field

c9db315

[SVLS-9359] document DD_* env var ordering constraint in README

302b180

[SVLS-9359] add WeakMap GC rationale to comment

a881fd4

[SVLS-9359] move env trackers to internal module and harden git tag u…

4eb6d10

…psert

[SVLS-9359] add setEnvironment method to seed construct-tracked env vars

82cb41d

ava-silver force-pushed the ava.silver/svls-9359/stop-reading-private-cdk-function-environment-field branch from f15ce72 to 82cb41d Compare August 13, 2026 20:54

ava-silver added 4 commits August 13, 2026 17:50

[SVLS-9359] clean up internal representation

9450386

[SVLS-9359] clean up readme

11f113a

[SVLS-9359] update comment

c676e9d

[SVLS-9359] update style

d2fb001

avangelillo approved these changes Aug 14, 2026

View reviewed changes

[SVLS-9359] clean up readme pt 2

231240e

TalUsvyatsky approved these changes Aug 14, 2026

View reviewed changes

ava-silver merged commit 0ba7bca into main Aug 14, 2026
9 of 10 checks passed

ava-silver deleted the ava.silver/svls-9359/stop-reading-private-cdk-function-environment-field branch August 14, 2026 17:52

ava-silver mentioned this pull request Aug 18, 2026

chore: Release v2-5.0.0 #681

Merged

Navigation Menu

Uh oh!

fix: stop reading private aws-cdk-lib Function.environment field - #621

fix: stop reading private aws-cdk-lib Function.environment field#621
ava-silver merged 10 commits into
mainfrom
ava.silver/svls-9359/stop-reading-private-cdk-function-environment-field

ava-silver commented Jun 23, 2026 •

edited

Loading

Uh oh!

ava-silver commented Jun 23, 2026

Uh oh!

This comment has been minimized.

janine-c left a comment

Uh oh!

Uh oh!

ahammond commented Aug 12, 2026

Uh oh!

ava-silver commented Aug 12, 2026

Uh oh!

ahammond commented Aug 13, 2026

Uh oh!

ava-silver commented Aug 13, 2026

Uh oh!

Uh oh!

ava-silver commented Aug 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

ava-silver commented Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Motivation

Changes

Behavior change

Testing Guidelines

Types of Changes

Check all that apply

Uh oh!

ava-silver commented Jun 23, 2026

Uh oh!

This comment has been minimized.

janine-c left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ahammond commented Aug 12, 2026

Uh oh!

ava-silver commented Aug 12, 2026

Uh oh!

ahammond commented Aug 13, 2026

Uh oh!

ava-silver commented Aug 13, 2026

Uh oh!

Uh oh!

ava-silver commented Aug 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

ava-silver commented Jun 23, 2026 •

edited

Loading